I love R markdown and use it on a daily basis for my analysis. This post provides a few tips I use to improve the appearance of my output documents. In any case, the bible is the Rstudio documentation.

1 Text formating

R markdown allows to easily format your text. You can add links, write in bold or italic. This is very well explained in the Rstudio cheatsheet.

Here is the code I used to make this paragraph:

R markdown allows to easily format your text. You can add [links](www.r-graph-gallery.com), write in **bold** or *italic*. This is very well explained in the [Rstudio cheatsheet](https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf).

2 Chapter auto numbering

Header of level 1, 2, 3 are set using #, ## and ###. You can auto number your chapters using this option the header:

---
title: "Your title"
output: 
  html_document:
    number_sections: TRUE
---

# Title
## A subtitle
## Another subtitle

# Another title

3 Skip a line

I really like to add spaces in my document to give it a more uncluttered look. This is done using the <br> command. This .rmd code:

A first sentence
<br><br><br><br>
A seconde sentence

will give this htmloutput

A first sentence

A seconde sentence

4 Center an image

Figure: this is an awesome figure

5 Add footer or header

You can add some html code at the beginning or at the end of your document. Here is the html code I’ve added at the end of this document:

&nbsp;
<hr />
<p style="text-align: center;">A work by <a href="https://github.com/holtzy/">Yan Holtz</a></p>
<p style="text-align: center;"><span style="color: #808080;"><em>Yan.holtz.data@gmail.com</em></span></p>

<!-- Add icon library -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">

<!-- Add font awesome icons -->
<p style="text-align: center;">
    <a href="https://twitter.com/r_graph_gallery?lang=en" class="fa fa-twitter"></a>
    <a href="https://www.linkedin.com/in/yan-holtz-2477534a/" class="fa fa-linkedin"></a>
    <a href="https://github.com/holtzy/" class="fa fa-github"></a>
</p>

&nbsp;

Put it in a footer.html file that you save in the folder of your .rmd file. Then ask to put it at the end of the document in the YAML header:

---
title: "Your title"
output: 
  html_document:
    includes:
      after_body: footer.html
---

Your footer should now look like this:

6 Add space before title

I find it pleasant to have a bit of space before starting a new chapter. You can use a <br> before each header. A more convenient way is to add some padding in your CSS. Create a style.css file:

h1, .h1, h2, .h2, h3, .h3 {
    margin-top: 84px;
}

A document that takes into account this .css file:

---
title: "A document with a CSS included"
output:
  html_document:
    css: style.css
---

A title will follow, but with a lot of space before it

# Title 1

content of part 1

# Title 2

content of part 2

7 Add caption to your figures

Specify the caption of your figure in the chunk header. Example:

{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure: Here is a really important caption."}

library(tidyverse)
mpg %>%
  ggplot( aes(x=reorder(class, hwy), y=hwy, fill=class)) + 
    geom_boxplot() +
    xlab("class") +
    theme(legend.position="none")

Figure: Here is a really important caption.

8 Custom caption

Change the black default caption using CSS. Adding this code in your style.css file.

<style>
p.caption {
  font-size: 0.9em;
  font-style: italic;
  color: grey;
  margin-right: 10%;
  margin-left: 10%;  
  text-align: justify;
}
</style>

file will give this result:

Figure: Here is a really important caption, customized to be grey and in italic.

9 Use buttons for sub-chapters

Save space in your document using buttons for sub chapters. Add this code at the end of your title:

# Use pills {.tabset .tabset-fade .tabset-pills}

Your subtitles will appear like that:

9.1 First

Note that I’ve custom the buttons using this CSS:

.btn {
    border-width: 0 0px 0px 0px;
    font-weight: normal;
    text-transform: ;
}
.btn-default {
    color: #2ecc71;
    background-color: #ffffff;
    border-color: #ffffff;
}

9.2 Second

content of sub-chapter #2

9.3 Third

content of sub-chapter #3

10 Use DT for tables

The DT library is my favourite option to display tables in your document. It allows to:

Show only a few line
Have a clean appearance
Have a research bar to find a specific entry
Add filters to each column
And much more

library(DT)
datatable(mtcars, rownames = FALSE, filter="top", options = list(pageLength = 5, scrollX=T) )

11 Hide code

If you share your code with somebody who’s more focus on results than code, or if your code chunks are very long, you probably want to hide the code, but still allow the reader to consult it if necessary. This is possible by modifying the YAML header of your document:

output:
  html_document:
    code_folding: "hide"

12 Highlight a piece of text

You can apply some css to a specific part of your document. Here is an example where I change the background color of a small part. Handy to highlight conclusions at the end of your document.

Code:

<style>
div.blue { background-color:#e6f0ff; border-radius: 5px; padding: 20px;}
</style>
<div class = "blue">

- This is my first conclusion
- This is my second conclusion

</div>

Will give:

This is my first conclusion
This is my second conclusion

13 Add a github link in the corner of your document

Several solutions exist. I used the code provided in this repo. Made by Tim Holman. Just paste the provided code in your header.html, like you have done for the footer.

14 Use interactive graphics.

R allows to build any type of interactive graphic. My favourite library is plotly that will turn any of your ggplot2 graphic interactive in one supplementary line of code. Try to hover points, to select a zone, to click on the legend.

library(ggplot2)
library(plotly)
library(gapminder)
 
p <- gapminder %>%
  filter(year==1977) %>%
  ggplot( aes(gdpPercap, lifeExp, size = pop, color=continent)) +
  geom_point() +
  scale_x_log10() +
  theme_bw()
 
ggplotly(p)

15 Use a template

Customize the document appearance using one of the existing template:

17 Compile several in a website

18 Create template

19 Add a session info

It is a good practice to add a session info at the end of your document. It will increase reproducibility and costs only one line of code

sessionInfo()

## R version 3.4.1 (2017-06-30)
## Platform: x86_64-apple-darwin15.6.0 (64-bit)
## Running under: macOS Sierra 10.12.6
## 
## Matrix products: default
## BLAS: /Library/Frameworks/R.framework/Versions/3.4/Resources/lib/libRblas.0.dylib
## LAPACK: /Library/Frameworks/R.framework/Versions/3.4/Resources/lib/libRlapack.dylib
## 
## locale:
## [1] en_AU.UTF-8/en_AU.UTF-8/en_AU.UTF-8/C/en_AU.UTF-8/en_AU.UTF-8
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
##  [1] bindrcpp_0.2    gapminder_0.3.0 plotly_4.7.1    DT_0.2         
##  [5] forcats_0.2.0   stringr_1.2.0   dplyr_0.7.4     purrr_0.2.4    
##  [9] readr_1.1.1     tidyr_0.7.2     tibble_1.4.2    ggplot2_2.2.1  
## [13] tidyverse_1.2.1 rmarkdown_1.8   epuRate_0.1    
## 
## loaded via a namespace (and not attached):
##  [1] reshape2_1.4.3      haven_1.1.0         lattice_0.20-35    
##  [4] colorspace_1.3-2    viridisLite_0.2.0   htmltools_0.3.6    
##  [7] yaml_2.1.16         rlang_0.1.6.9003    pillar_1.1.0       
## [10] foreign_0.8-69      glue_1.2.0          modelr_0.1.1       
## [13] readxl_1.0.0        bindr_0.1           plyr_1.8.4         
## [16] munsell_0.4.3       gtable_0.2.0        cellranger_1.1.0   
## [19] rvest_0.3.2         htmlwidgets_1.1     psych_1.7.8        
## [22] evaluate_0.10.1     labeling_0.3        knitr_1.18.7       
## [25] httpuv_1.3.5        crosstalk_1.0.0     parallel_3.4.1     
## [28] highr_0.6           broom_0.4.2         Rcpp_0.12.14       
## [31] xtable_1.8-2        scales_0.5.0.9000   backports_1.1.1    
## [34] jsonlite_1.5        mime_0.5            mnormt_1.5-5       
## [37] hms_0.3             digest_0.6.14       stringi_1.1.5      
## [40] shiny_1.0.5         grid_3.4.1          rprojroot_1.2      
## [43] cli_1.0.0           tools_3.4.1         magrittr_1.5       
## [46] lazyeval_0.2.1      crayon_1.3.4        pkgconfig_2.0.1    
## [49] data.table_1.10.4-3 xml2_1.1.1          lubridate_1.7.1    
## [52] assertthat_0.2.0    httr_1.3.1          rstudioapi_0.7     
## [55] R6_2.2.2            nlme_3.1-131        compiler_3.4.1

A work by Yan Holtz

Yan.holtz.data@gmail.com

A few tips for R Markdown

by Yan Holtz - 20 February 2018

1 Text formating

2 Chapter auto numbering

3 Skip a line

4 Center an image

5 Add footer or header

6 Add space before title

7 Add caption to your figures

8 Custom caption

9 Use buttons for sub-chapters

9.1 First

9.2 Second

9.3 Third

10 Use DT for tables

11 Hide code

12 Highlight a piece of text

13 Add a github link in the corner of your document

14 Use interactive graphics.

15 Use a template

17 Compile several in a website

18 Create template

19 Add a session info

A few tips for R Markdown

by Yan Holtz - 20 February 2018

1 Text formating

2 Chapter auto numbering

3 Skip a line

4 Center an image

5 Add footer or header

6 Add space before title

7 Add caption to your figures

8 Custom caption

9 Use buttons for sub-chapters

9.1 First

9.2 Second

9.3 Third

10 Use DT for tables

11 Hide code

12 Highlight a piece of text

13 Add a github link in the corner of your document

14 Use interactive graphics.

15 Use a template

16 Share it online

17 Compile several in a website

18 Create template

19 Add a session info